Skip to content

docs(spec): Button and IconButton take a surface prop for glass on native; other native looks stay theme intent - #12801

Draft
cixzhang wants to merge 3 commits into
mainfrom
lane2/ast082-glass-surface
Draft

cixzhang wants to merge 3 commits into
mainfrom
lane2/ast082-glass-surface

Conversation

@cixzhang

@cixzhang cixzhang commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Records only. On native platforms, a Button or IconButton can take a glass appearance at one call site: they take a surface prop, plain or glass. Left unset, a button looks as it does today. Every other native-only look stays in the theme, and which other surfaces get a prop like this is a new open question.

Exact decision needed

None: the owner decided it (spec:AST-082 DEC-2's amendment). This pull request records it.

Existing authority searched

  • spec:AST-082 DEC-2 (native-only visuals are theme configuration, not component props; "Rejected: visual props for one platform on components"), DEC-6 (platform props carry behavior and presentation choices), FR3 (core and platform contracts), and Open questions OQ1–OQ6.
  • Terms searched: surface, glass, native-only, visual props.

Overlap checked: #12707, #12699, #12557, #8500, #8288, #9369 (#9369 would make current a Swift Button record that decides glass with no new prop or modifier and keeps macOS and iOS before 26 on the token look; that record follows the amended DEC-2 before it becomes current; #8500 and #8288 edit spec:AST-093's Current-state impact, not FR4 or its verification row; #12707 records the separate contracts decision in spec:AST-082 FR3, DEC-7 and DEC-17, and a merge-tree check against it is clean; #12699 adds only an FR4 ref bullet; one decision per pull request, so this is separate; #12557 drafts spec:AST-123 and touches no spec:AST-082 text)

Decision

  • DEC-2, amended: Button and IconButton take a per-call-site surface prop (plain or glass) as a situational appearance choice. It is a platform prop in every native platform's contract (FR3, FR5); the core and web contracts do not have it, because FR3 says a platform never offers a prop it does not fully honor. surface has no default: unset follows the theme's native material intent and the platform's placement rule, and plain or glass overrides them. Where a platform or OS version has no system glass, glass draws that platform's chrome material; Reduce Transparency and Increase Contrast apply as for any glass. Every other native-only look stays theme intent. DEC-2's original text stays. Its "Rejected: visual props … on components" line gets an "Amended:" note that names Button and IconButton as the one exception.
  • spec:AST-093 FR4: "never adds a visual prop for one platform" now names Button and IconButton's surface prop as the exception, so the two records agree. Its verification row's failure signal names the same exception.
  • OQ7 (new): which other surfaces take surface-specific props, and where they live in the contracts.
  • Owner decision, 2026-11-18 13:08 PT: she chose "a surface prop on Button".

Why a per-call-site prop (spec:AST-002 FR5)

Take two otherwise identical buttons in the same view. One shows while the app presents that view with native appearance, and the other while the app presents it with non-native appearance (for example, a surface that moves components between native and non-native appearance). Only the app knows which presentation it is in at that call site. Button cannot derive it from its placement or from the theme alone, so the choice is made at the call site.

Rejected alternatives

  • Glass as theme intent only, with no prop. DEC-2's original rule stays the default, and this decision makes the one exception.

Claim scope and non-goals

Evidence and implementation relationship

None needed: this records the owner's decision.

Writing rubric results

  • R1 narration: none in the requirements. DEC-2's amendment is a dated "Amended …" paragraph inside the decision, the form spec:AST-030 uses for amended decisions.
  • R2 research in the record: none.
  • R3 evidence naming a change: none.
  • R4 rejected alternatives over one line or outside a decision: none. DEC-2 keeps its one Rejected: sentence, with an "Amended:" note.
  • R5 pull request or issue references remaining: none.
  • R6 ruled open questions still listing options: none. OQ7 is open and lists no options.
  • R7 project status (build status or work order): none.

Scope

Components: Button, IconButton (record: spec:AST-082)

  • This PR contains specification records only.
  • It records observable behavior and preserves equivalent internal implementations.
  • Any named internal mechanism is intentionally public, names its dependent caller/system, and explains why an equivalent implementation would not satisfy the contract.
  • Verification states the evidence layer and failure signal without prescribing CI job/workflow topology.
  • It records one intentional durable decision, not a rescue for a separable tagalong.
  • The canonical knowledge owner, affected current claims, and overlapping open work are named; any ownership collision is resolved or called out for human decision.
  • Adjacent API, visual, accessibility, composition, and implementation facts remain outside scope unless this exact decision depends on them.
  • Public text and artifacts contain no internal Meta context.

Validation

  • pnpm check:knowledge: templates and records aligned.
  • Prettier: clean.
  • git diff --check: clean.

@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 19, 2026 4:41am UTC

Request Review

@astracat-bot

astracat-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
❓ Needs maintainer input (for maintainers only) Nov 19, 2026, 4:50 AM UTC

@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 19, 2026
@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 19, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This spec change waits on an engineering owner's decision, and two record fixes are needed either way.

Decision needed: the amended DEC-2 in spec:AST-082 reverses a current decision that rejects visual props for one platform, so approval waits on an engineering owner recording the decision by commenting /approve-spec <full head SHA> on this pull request (the author may do so as an engineering owner). That approval should also settle three things: which contract holds surface, how it combines with the theme's native material intent and the Swift Button's placement-derived glass, and whether IconButton is covered.

Blocking findings:

  • spec:AST-093 FR4 still says a native component "never adds a visual prop for one platform (spec:AST-082/DEC-2)", so amend it in this pull request to name the Button and IconButton surface exception.
  • "Typed from the shared contracts" reads as the core contract, because current records call the core contract the shared one, and under FR3 that would make the web Button and IconButton honor glass, so name the contract that holds surface and say what glass draws where the platform or OS version has no system glass.

Before approval, the description also needs the admission argument spec:AST-002 FR5 asks for: the two otherwise identical cases, why the caller knows the difference, and why Button cannot derive it from its placement.

Claims and files checked

Review mode: full; reason: no-earlier-review

  • Claim: records only, one knowledge record changed. Verified.
  • Claim: Button and IconButton take surface, plain by default or glass. Verified in the DEC-2 amendment.
  • Claim: every other native-only look stays theme intent. Verified.
  • Claim: DEC-2's original text stays, with an "Amended:" note on its rejected alternative. Verified; the decider line is unchanged.
  • Claim: a new OQ7 is open and lists no options. Verified.
  • Claim: the owner chose a surface prop on Button. The record also covers IconButton; left to the approval.
  • Claim: no decision is needed. False: the spec-owner approval check still waits on an engineering owner.
  • Claim: overlapping open work is separate and merges cleanly. Verified for the contracts and ref-prop changes; the React Native glass draft touches no text here.
  • Claim: affected current claims are named. False: spec:AST-093 FR4 is not named.
  • Claim: writing rubric clean, knowledge check aligned, Prettier and whitespace clean. Verified.
  • Claim: no internal context in public text. Verified.
  • File docs/specs/AST-082-native-first-surfaces/spec.md: the two blocking findings above.

Automated review (maintainer link)

…ls back to chrome material; AST-093 FR4 names the exception

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This spec change still waits on an engineering owner's decision, and four record fixes are needed either way.

Decision needed: the amended DEC-2 in spec:AST-082 reverses a current decision that rejects visual props for one platform, so approval waits on an engineering owner recording the decision by commenting /approve-spec <full head SHA> on this pull request, on the head that carries the fixes below (the author may do so as an engineering owner). That approval should also confirm that IconButton is meant beside Button, and the surface name beside FR10's existing material intent.

Blocking findings:

  • surface is placed in the iOS and Android contracts only, but FR3 says one API serves every platform a language's apps run on and a prop scoped to one of them states its reason, so add macOS (and say whether Windows) or state why macOS has no honest glass.
  • The amendment calls plain the default but also says an unset surface follows the theme's material and the placement rule, which draws glass in a system bar where plain would not, so say that surface has no default (unset follows the theme and placement, and plain or glass overrides them) or drop the unset sentence.
  • Miss: the verification row for spec:AST-093 FR4 still fails "a platform-only visual prop is added", so extend it with the same Button and IconButton surface exception.
  • The description says glass falls back "with no warning" and that no open pull request edits spec:AST-093, but the record says nothing about warnings and #8288 and #8500 edit that record's Current-state impact, so align the description with the record and name those two in the overlap line.

The earlier findings on the spec:AST-093 FR4 requirement and on which contract holds surface are fixed, and the admission argument is now in the description.

Claims and files checked

Review mode: full; reason: spec-record

  • Claim: records only, two knowledge records changed. Verified.
  • Claim: Button and IconButton take surface, plain by default or glass. Verified in the amendment; the default conflicts with the unset rule (second finding).
  • Claim: it is a platform prop in the iOS and Android contracts, not in the core or web contracts. Verified; macOS is left out without a reason (first finding).
  • Claim: an explicit surface decides, and an unset one follows the theme's native material intent and the placement rule. Verified.
  • Claim: without system glass, glass draws the platform's chrome material with no warning, and accessibility settings apply as for any glass. Partly false: the record says nothing about warnings (fourth finding).
  • Claim: every other native-only look stays theme intent. Verified.
  • Claim: DEC-2's original text stays, with an "Amended:" note on its rejected alternative. Verified; the decider line is unchanged.
  • Claim: spec:AST-093 FR4 names the exception, so the two records agree. Verified for the requirement; its verification row still disagrees (third finding).
  • Claim: a new OQ7 is open and lists no options. Verified.
  • Claim: the owner chose a surface prop on Button. The record also covers IconButton; left to the approval.
  • Claim: no decision is needed. False: the spec-owner approval check still waits on an engineering owner.
  • Claim: overlapping open work is separate and merges cleanly, and no open pull request edits spec:AST-093. The named pull requests merge cleanly; two older open pull requests edit spec:AST-093 elsewhere (fourth finding).
  • Claim: the admission argument for a per-call-site prop. Present: the two cases, the caller's knowledge and why Button cannot derive it are named; the outcomes are implied.
  • Claim: writing rubric clean, the amendment follows the dated-amendment form, knowledge check aligned, Prettier and whitespace clean. Verified.
  • Claim: no internal context in public text. Verified.
  • File docs/specs/AST-082-native-first-surfaces/spec.md: first and second findings.
  • File docs/specs/AST-093-native-component-guidelines/spec.md: third finding.

Automated review (maintainer link)

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This spec change is ready for an engineering owner's decision, with one description fix.

Decision needed: the amended DEC-2 in spec:AST-082 reverses a current decision that rejects visual props for one platform, so approval waits on an engineering owner recording the decision by commenting /approve-spec <full head SHA> on this pull request (the author may do so as an engineering owner). That approval should also confirm that IconButton is meant beside Button, and the surface name beside FR10's existing material intent.

Blocking finding:

  • Miss: the overlap list leaves out #9369, which would make current a Swift Button record that decides glass with "no new prop or modifier" and keeps macOS and iOS before 26 on the token look, so name it and say that record follows the amended DEC-2 before it becomes current (a description edit, which does not move the head).

All four record and description fixes from the last review are in.

Claims and files checked

Review mode: full; reason: spec-record

  • Claim: records only, two knowledge records changed. Verified.
  • Claim: Button and IconButton take surface, plain or glass, and an unset button looks as it does today. Verified in the DEC-2 amendment: unset follows the theme and the placement rule.
  • Claim: every other native-only look stays in the theme, and a new open question asks which other components get such a prop. Verified (OQ7).
  • Claim: no decision is needed because the owner decided it. Not verified: the amendment's decider line names the owner, but the spec-owner approval check still waits on an approval at this head.
  • Claim: the existing authority searched was DEC-2, DEC-6, FR3 and OQ1 to OQ6. Verified as read; the "behavior and presentation choices" wording is DEC-2's own sentence citing DEC-6.
  • Claim: the named overlapping pull requests are separate, the two that edit the same record merge cleanly, and two others touch only the Current-state impact of spec:AST-093. Verified; #9369 is missing from the list (blocking finding).
  • Claim: surface is a platform prop in every native platform's contract, not in the core or web contracts. Verified; the record itself gives no reason for leaving the web out.
  • Claim: surface has no default; unset follows the theme's native material intent and the placement rule, and a set value overrides them. Verified.
  • Claim: without system glass, glass draws the platform's chrome material, and Reduce Transparency and Increase Contrast apply as for any glass. Verified; the record leaves chrome material to each platform's record.
  • Claim: DEC-2's original text stays, with an "Amended:" note on its rejected alternative. Verified; the decider line is unchanged.
  • Claim: spec:AST-093 FR4 and its verification row name the same exception. Verified.
  • Claim: OQ7 is open and lists no options. Verified.
  • Claim: the owner chose a surface prop on Button. The record also covers IconButton; left to the approval.
  • Claim: the admission argument for a per-call-site prop. Present: the two cases, the caller's knowledge and why Button cannot derive it are named; the outcomes are implied.
  • Claim: no other component gains a surface prop here, and the React Native draft can cite the amended decision once this merges. Verified.
  • Claim: writing rubric clean, the dated-amendment form spec:AST-030 uses, knowledge check aligned, Prettier and whitespace clean. Verified.
  • Claim: no internal context in public text. Verified.
  • File docs/specs/AST-082-native-first-surfaces/spec.md: clear.
  • File docs/specs/AST-093-native-component-guidelines/spec.md: clear.

Automated review (maintainer link)

This branch was successfully deployed

1 active deployment
Preview — daa65a8a Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot. needs:spec-owner-review Current knowledge records await owner approval

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant